OracleAS Portlet Developer Kit (PDK)
Installing Oracle Java Portlet Container

Contents

Introduction
Prerequisites
Installing Oracle Java Portlet Container
Deploying JSR 168 portlet applications
Adding Portlets to a Page

Introduction

Oracle Java Portlet Container enables you to quickly and easily build and run interoperable Java portlets. The container provides a runtime environment for Java portlets coded to the standard Java Portlet Specification (JSR 168) APIs that enables the portlets to be utilized by any portal client supporting the OASIS WSRP 1.0 standard, including OracleAS Portal or the OracleAS Portal Verification Service. The Oracle Java Portlet Container also supports the preliminary version of WSRP 2.0.

This document is an installation and configuration guide for Oracle Java Portlet Container. In this document, you will learn how to:

• Set up and configure Oracle Java Portlet Container and sample portlets
• Register your portlets with a WSRP-enabled consumer

Prerequisites

Before you begin to install and configure Oracle Java Portlet Container, make sure that:

1. You have an application server meeting the minimum requirements stated in the release notes.

Installing Oracle Java Portlet Container

This section describes the configuration requirements for two of the more common portlet scenarios: configuring Oracle Containers for J2EE (OC4J) in Oracle Application Server and configuring a standalone OC4J. If you have Oracle Application Server 10.1.3.2.0, then you already have an OC4J that is preconfigured to run portlet producers (OC4J_WebCenter). If you prefer not to use OC4J_WebCenter, or if you are installing the portlet container on a standalone OC4J, then follow the steps in this section.

If you are installing the portlet container to a standalone OC4J then it is assumed that you have already downloaded and unpackaged the pdk software archive into a directory located on the same machine as your OC4J instance. The remainder of the instructions contained in this document will refer to this directory as $unzip_directory.

To configure an application server OC4J instance or a standalone OC4J to run portlets, perform the following steps. The application consoles in an Application Server or standalone OC4J instance are similar but not identical. The instructions state where extra steps for one or the other environment are necessary.

1. For an OC4J that is part of Oracle Application Server, create a new OC4J instance into which you can deploy your portlets:

   1. Log in to the Application Server Control Console as oc4jadmin at:

      http://<host_name>:<port_number>/em

      For example:

      http://localhost:8888/em
   2. On the Cluster Topology page, click the link to your application server.
   3. Under System Components, click the Create OC4J Instance button.
   4. On the Create OC4J Instance page, specify a name for the OC4J instance.

      For example, to create a separate instance for WSRP producers, you might name the instance wsrp. You can use any name you prefer.

   5. Make sure the Start this OC4J instance after creation check box is not selected.

   6. Click Create.

   For a standalone OC4J, stop the standalone OC4J in the Application Server Control Console:

   1. Log in to Application Server Control as oc4jadmin at:

      http://host_name:port_number/em

      For example:

      http://localhost:8888/em
   2. On the OC4J home page, click Stop.
2. If required, set up a preference store. Portlet producers use a File preference store by default. The File preference store is configured and ready to use out of the box. For high availability, you can configure the preference store to use a database instead. Using a database preference store requires additional configuration. If deploying to a standalone OC4J the scripts located in $unzip_directory/portlet-container can be used to set up the database preference store. Section 16.4 of the Oracle WebCenter Developer's Guide describes how to use these scripts.
3. Set up the portlet server shared libraries using the portlet server install tool which is located in $unzip_directory/portlet-container. It is run thus,

   java -jar portlet-server-install.jar $J2EE_HOME

4. Start OC4J by navigating to ORACLE_HOME\bin (where ORACLE_HOME is the source location of your OC4J) and running the following command:

   oc4j -start
5. Test the configuration to confirm it is working correctly.

   You can use the sample WSRP producer, wsrp-samples.ear, for this purpose.

   To deploy the sample portlets EAR file, perform the following steps:

   1. Return to the Application Server Control Console.

      Log in to Application Server Control as oc4jadmin at:

      http://host_name:port_number/em

      For example:

      http://localhost:8888/em
   2. On Oracle Application Server, click the Oracle Application Server middle-tier instance to which you plan to deploy portlets.
   3. On Oracle Application Server, click the OC4J instance that you created earlier, wsrp.
   4. Click the Applications tab.
   5. Click Deploy.

      The 'Deploy: Select Archive' page is displayed.

   6. Select Archive is present on local host. Upload the archive to the server where Application Server Control is running.

   7. In Archive Location, enter the path to and the filename wsrp-samples.ear. This is located in $unzip_directory/portlet-container.

   8. Select Automatically create a new deployment plan.

   9. Click Next.

      Wait while the system uploads the EAR file. When the file is uploaded, the 'Deploy: Application Attributes' page is displayed.

   10. For Application Name, enter sampleportlets.

   11. For Context Root:

       For a standalone OC4J, enter portletapp.

       For the Application Server instance, enter some other name that is not already in use.

   12. Click Next.

       The 'Deploy: Deployment Settings' page is displayed.

   13. Click Deploy.

       You can alter any deployment settings on this page, but, in this case, just click 'Deploy'.

       The 'Deployment Confirmation' page is displayed.

   14. Carefully check the settings to ensure that they are correct.

   15. Click Return to dismiss the Confirmation page.

6. Once the sample EAR file is deployed, test its WSDL URL by entering it into a browser.

   For the WSDL URL syntax, use the following structure:

   http://<host>:<port>/portletapp/info

   The Web page describes the portlets available in the sample portlet application and provides links to v1 and v2 WSDL urls.

7. Copy the link location of one of the portlet producers listed under WSDL URLS, and register this portlet producer by following the instructions in section 16.10 of the Oracle WebCenter Framework Developer's Guide.

   Further test the configuration by adding some of the sample portlets from the newly registered portlet producer to a page and displaying the page. If the registration fails for any reason or you cannot add portlets to a page, then refer to Appendix E, "Troubleshooting WebCenter Applications" in the Oracle WebCenter Framework Developer's Guide.

Deploying JSR 168 portlet applications

This applies to portlet applications deployed in previous versions of the portlet container. The EAR file should be pre-configured as described above and the portlet preference store should be migrated as described in Appendix B4 of the Oracle WebCenter Framework Developer's Guide.

Note: The wsrp-samples.ear file already contains the relevant WSRP configuration and does not need to be preconfigured before deployment to the portlet server.

Adding Portlets to a Page

You have now successfully installed Oracle Java Portlet Container. You can now:

• Add portlets to an Oracle WebCenter page (refer to the Oracle WebCenter Framework Developer's Guide for more information). This may be done using either of the WSDL urls. 
• Begin building your own Java portlets.  (Use the Java Portlet Wizard or refer to the Oracle WebCenter Framework Developer's Guide for detailed information on building Java portlets.)